Text Translation (preview:2025-10-01)

2025/12/15 • 3 updated methods

GetSupportedLanguages (updated)
Description :  Gets the set of languages currently supported by other operations of the Translator.
Reference :  Link ¶

⚶ Changes

{
  "#id": "GetSupportedLanguages",
  "$responses": {
    "200": {
      "$properties": {
        "@added_e8305535368f426abc1bd6c43b2ba685": {
          "#name": "models",
          "Description": "LLM models supported.",
          "Required": false,
          "Type": "array",
          "$items": {
            "Type": "string"
          }
        },
        "@removed_d0f0632fe4294624b42e9f7b493f48de": {
          "#name": "dictionary",
          "Description": "Languages that support dictionary API.",
          "Required": false,
          "Type": "object"
        }
      }
    }
  }
}

⚼ Request

GET:  /languages
{
X-ClientTraceId:
{
Description: A client-generated GUID to uniquely identify the request. ,
Required: False ,
}
string ,
scope:
{
Description: A comma-separated list of names defining the group of languages to return. Allowed group names are: `translation`, `transliteration` and `dictionary`. If no scope is given, then all groups are returned, which is equivalent to passing `scope=translation,transliteration,dictionary`. To decide which set of supported languages is appropriate for your scenario, see the description of the [response object](#response-body). ,
Required: False ,
}
string ,
Accept-Language:
{
Description: The language to use for user interface strings. Some of the fields in the response are names of languages or names of regions. Use this parameter to define the language in which these names are returned. The language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` to request names in French or use the value `zh-Hant` to request names in Chinese Traditional. Names are provided in the English language when a target language is not specified or when localization is not available. ,
Required: False ,
}
string ,
If-None-Match:
{
Description: Passing the value of the ETag response header in an If-None-Match field will allow the service to optimize the response. If the resource has not been modified, the service will return status code 304 and an empty response body. ,
Required: False ,
}
string ,
api-version:
{
Description: Mandatory API version parameter ,
Required: True ,
}
string ,
}

⚐ Response (200)

{
$headers:
{
etag:
{
Description: Current value of the entity tag for the requested groups of supported languages. To make subsequent requests more efficient, the client may send the `ETag` value in an `If-None-Match` header field. ,
}
string ,
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
}
,
$schema:
{
Description: Response for the languages API. ,
}
{
translation:
{
Description: Languages that support translate API. ,
Required: False ,
}
object ,
transliteration:
{
Description: Languages that support transliteration API. ,
Required: False ,
}
object ,
models:
{
Description: LLM models supported. ,
Required: False ,
}
[
string ,
]
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
}
,
$schema:
{
Description: Representation of the Error Response from Translator Service. ,
}
{
error:
{
Description: Error details. ,
Required: True ,
}
{
code:
{
Description: String identifier of the error. ,
Required: True ,
}
string ,
message:
{
Description: Human readable error description. ,
Required: True ,
}
string ,
}
,
}
,
}
Translate (updated)
Description :  Translate Text
Reference :  Link ¶

⚶ Changes

{
  "#id": "Translate",
  "$parameters": {
    "body": {
      "Description": {
        "new": "Request data for translate.",
        "old": "Request body for the translate API."
      },
      "$properties": {
        "inputs": {
          "$properties": {
            "targets": {
              "Description": {
                "new": "Target language and translation configuration parameters.",
                "old": "Translate targets parameters"
              },
              "$properties": [
                {
                  "#name": "deploymentName",
                  "Description": {
                    "new": "Default is 'general', which uses NMT system.\n'abc-inc-gpt-4o', and 'abc-inc-gpt-4o-mini' are examples of deployment names which use GPT-4o uses or\nGPT-4o-mini model. 'gpt-4o' uses GPT-4o model.\n\n'' uses the custom NMT model tuned by customer.\n'best' system determines which is the best model to use for the request. This intelligence could be introduced\nin future. Customer should have deployed it in their resource.\n",
                    "old": "Default is \u2018general\u2019, which uses NMT system.\n\u2018abc-inc-gpt-4o\u2019, and \u2018abc-inc-gpt-4o-mini\u2019 are examples of deployment names which use GPT-4o uses or \nGPT-4o-mini model. \u2018gpt-4o\u2019 uses GPT-4o model. \n\n\u2018\u2019 uses the custom NMT model tuned by customer.\n\u2018best\u2019 system determines which is the best model to use for the request. This intelligence could be introduced\nin future. Customer should have deployed it in their resource.\n"
                  }
                },
                {
                  "#name": "referenceTextPairs",
                  "Description": {
                    "new": "Reference text pairs to generate adaptive customized translation.",
                    "old": "Reference sentence pairs to generate adaptive results."
                  },
                  "$items": {
                    "Description": {
                      "new": "Reference text pair to generate adaptive customized translation.",
                      "old": "Reference sentence pair."
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  },
  "$responses": {
    "200": {
      "$properties": {
        "value": {
          "$properties": {
            "translations": {
              "$properties": [
                {
                  "#name": "sourceCharacters",
                  "Description": {
                    "new": "An integer indicating the number of characters in the source text string",
                    "old": "An interger indicating the number of characters in the source text string"
                  }
                },
                {
                  "#name": "instructionTokens",
                  "Description": {
                    "new": "An integer indicating the number of tokens used in generating the translated text",
                    "old": "An interger indicating the number of tokens used in generating the translated text"
                  }
                },
                {
                  "#name": "sourceTokens",
                  "Description": {
                    "new": "An integer indicating the number of tokens used in the source sentence",
                    "old": "An interger indicating the number of tokens used in the source sentence"
                  }
                },
                {
                  "#name": "responseTokens",
                  "Description": {
                    "new": "An integer indicating the number of tokens used in the translation response",
                    "old": "An interger indicating the number of tokens used in the translation response"
                  }
                },
                {
                  "#name": "targetTokens",
                  "Description": {
                    "new": "An integer indicating the number of tokens used in the target sentence",
                    "old": "An interger indicating the number of tokens used in the target sentence"
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

⚼ Request

POST:  /translate
{
X-ClientTraceId:
{
Description: A client-generated GUID to uniquely identify the request. ,
Required: False ,
}
string ,
api-version:
{
Description: Mandatory API version parameter ,
Required: True ,
}
string ,
body:
{
Description: Defines the content of the request ,
Required: True ,
}
{
inputs:
{
Description: Array of the input text elements to translate. ,
Required: True ,
}
[
{
text:
{
Description: Text to translate. ,
Required: True ,
}
string ,
script:
{
Description: Specifies the script of the input text. ,
Required: False ,
}
string ,
language:
{
Description: Specifies the language of the input text. Find which languages are available to translate by looking up supported languages using the translation scope. If the language parameter isn't specified, automatic language detection is applied to determine the source language. You must use the language parameter rather than autodetection when using the dynamic dictionary feature. Note: the dynamic dictionary feature is case-sensitive. ,
Required: False ,
}
string ,
textType:
{
Description: Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Possible values are: plain (default) or html. ,
Enum:
{
Plain: Plain text. ,
Html: HTML-encoded text. ,
}
,
Required: False ,
}
enum ,
targets:
{
Description: Translation target parameters. ,
Required: True ,
}
[
{
language:
{
Description: Specifies the language of the output text. The target language must be one of the supported languages included in the translation scope. It's possible to translate to multiple languages simultaneously by including multiple string values in the targetsLanguage array. ,
Required: True ,
}
string ,
script:
{
Description: Specifies the script of the translated text. ,
Required: False ,
}
string ,
profanityAction:
{
Description: Specifies how profanities should be treated in translations. Possible values are: NoAction (default), Marked or Deleted. ,
Enum:
{
NoAction: No Action is taken on profanity ,
Marked: Profanity is marked. ,
Deleted: Profanity is deleted from the translated text. ,
}
,
Required: False ,
}
enum ,
profanityMarker:
{
Description: Specifies how profanities should be marked in translations. Possible values are: Asterisk (default) or Tag. ,
Enum:
{
Asterisk: Profanity is marked with asterisk. ,
Tag: Profanity is marked with the tags. ,
}
,
Required: False ,
}
enum ,
deploymentName:
{
Description: Default is 'general', which uses NMT system. 'abc-inc-gpt-4o', and 'abc-inc-gpt-4o-mini' are examples of deployment names which use GPT-4o uses or GPT-4o-mini model. 'gpt-4o' uses GPT-4o model. '' uses the custom NMT model tuned by customer. 'best' system determines which is the best model to use for the request. This intelligence could be introduced in future. Customer should have deployed it in their resource. ,
Required: False ,
}
string ,
allowFallback:
{
Description: In the case where a custom system is being used, specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. In the case where a Large Language Model is being used, specifies that the service is allowed to fall back to a Small Language Model if an error occurs. Possible values are: true (default) or false. allowFallback=false specifies that the translation should only use systems trained for the category specified by the request. If a translation for language X to language Y requires chaining through a pivot language E, then all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. If no system is found with the specific category, the request will return a 400 status code. allowFallback=true specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. ,
Required: False ,
}
boolean ,
grade:
{
Description: Defines complexity of LLM prompts to provide high accuracy translation. ,
Required: False ,
}
string ,
tone:
{
Description: Desired tone of target translation. ,
Required: False ,
}
string ,
gender:
{
Description: Desired gender of target translation. ,
Required: False ,
}
string ,
adaptiveDatasetId:
{
Description: Reference dataset ID having sentence pair to generate adaptive customized translation. ,
Required: False ,
}
string ,
referenceTextPairs:
{
Description: Reference text pairs to generate adaptive customized translation. ,
Required: False ,
}
[
{
source:
{
Description: Source reference sentence. ,
Required: True ,
}
string ,
target:
{
Description: Target reference sentence. ,
Required: True ,
}
string ,
}
,
]
,
}
,
]
,
}
,
]
,
}
,
}

⚐ Response (200)

{
$headers:
{
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
x-metered-usage:
{
Description: Specifies consumption (the number of characters for which the user will be charged) for the translation job request. For example, if the word "Hello" is translated from English (en) to French (fr), this field will return the value '5'. ,
}
integer ,
x-mt-system:
{
Description: Specifies the system type that was used for translation for each 'to' language requested for translation. The value is a comma-separated list of strings. Each string indicates a type: * Custom - Request includes a custom system and at least one custom system was used during translation. * Team - All other requests ,
}
string ,
}
,
$schema:
{
Description: Response for the translation API. ,
}
{
value:
{
Description: Array of the translated text elements. ,
Required: True ,
}
[
{
detectedLanguage:
{
Description: The detectedLanguage property is only present in the result object when language auto-detection is requested. ,
Required: False ,
}
{
language:
{
Description: A string representing the code of the detected language. ,
Required: True ,
}
string ,
score:
{
Description: A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence. ,
Format: float ,
Required: True ,
}
number ,
}
,
translations:
{
Description: An array of translation results. The size of the array matches the number of target languages specified through the to query parameter. ,
Required: True ,
}
[
{
language:
{
Description: A string representing the language code of the target language. ,
Required: True ,
}
string ,
sourceCharacters:
{
Description: An integer indicating the number of characters in the source text string ,
Format: int32 ,
Required: False ,
}
integer ,
instructionTokens:
{
Description: An integer indicating the number of tokens used in generating the translated text ,
Format: int32 ,
Required: False ,
}
integer ,
sourceTokens:
{
Description: An integer indicating the number of tokens used in the source sentence ,
Format: int32 ,
Required: False ,
}
integer ,
responseTokens:
{
Description: An integer indicating the number of tokens used in the translation response ,
Format: int32 ,
Required: False ,
}
integer ,
targetTokens:
{
Description: An integer indicating the number of tokens used in the target sentence ,
Format: int32 ,
Required: False ,
}
integer ,
text:
{
Description: A string giving the translated text. ,
Required: True ,
}
string ,
}
,
]
,
}
,
]
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
}
,
$schema:
{
Description: Representation of the Error Response from Translator Service. ,
}
{
error:
{
Description: Error details. ,
Required: True ,
}
{
code:
{
Description: String identifier of the error. ,
Required: True ,
}
string ,
message:
{
Description: Human readable error description. ,
Required: True ,
}
string ,
}
,
}
,
}
Transliterate (updated)
Description :  Transliterate Text
Reference :  Link ¶

⚶ Changes

{
  "#id": "Transliterate",
  "$parameters": {
    "body": {
      "Description": {
        "new": "Request data for transliterate.",
        "old": "Request body for the transliterate API."
      }
    }
  }
}

⚼ Request

POST:  /transliterate
{
X-ClientTraceId:
{
Description: A client-generated GUID to uniquely identify the request. ,
Required: False ,
}
string ,
language:
{
Description: Specifies the language of the text to convert from one script to another. Possible languages are listed in the transliteration scope obtained by querying the service for its supported languages. ,
Required: True ,
}
string ,
fromScript:
{
Description: Specifies the script used by the input text. Look up supported languages using the transliteration scope, to find input scripts available for the selected language. ,
Required: True ,
}
string ,
toScript:
{
Description: Specifies the output script. Look up supported languages using the transliteration scope, to find output scripts available for the selected combination of input language and input script. ,
Required: True ,
}
string ,
api-version:
{
Description: Mandatory API version parameter ,
Required: True ,
}
string ,
body:
{
Description: Defines the content of the request ,
Required: True ,
}
{
inputs:
{
Description: Array of the input text elements to transliterate. ,
Required: True ,
}
[
{
text:
{
Description: Text to translate. ,
Required: True ,
}
string ,
}
,
]
,
}
,
}

⚐ Response (200)

{
$headers:
{
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
}
,
$schema:
{
Description: Response for the transliteration API. ,
}
{
value:
{
Description: Array of transliterated texts ,
Required: True ,
}
[
{
text:
{
Description: A string which is the result of converting the input string to the output script. ,
Required: True ,
}
string ,
script:
{
Description: A string specifying the script used in the output. ,
Required: True ,
}
string ,
}
,
]
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-requestid:
{
Description: Value generated by the service to identify the request. It is used for troubleshooting purposes. ,
}
string ,
}
,
$schema:
{
Description: Representation of the Error Response from Translator Service. ,
}
{
error:
{
Description: Error details. ,
Required: True ,
}
{
code:
{
Description: String identifier of the error. ,
Required: True ,
}
string ,
message:
{
Description: Human readable error description. ,
Required: True ,
}
string ,
}
,
}
,
}